JavaScript aszinkron kontextus propagáció: Kérések nyomkövetése és folytatása az AsyncLocalStorage segítségével

A modern szerveroldali JavaScript-fejlesztésben, különösen a Node.js esetében, az aszinkron műveletek mindenütt jelen vannak. Az állapot és a kontextus kezelése ezeken az aszinkron határokon keresztül kihívást jelenthet. Ez a blogbejegyzés az aszinkron kontextus propagáció fogalmát vizsgálja, különös tekintettel arra, hogyan használható az AsyncLocalStorage a kérések nyomon követésének és folytatásának hatékony megvalósítására. Megvizsgáljuk előnyeit, korlátait és valós alkalmazásait, gyakorlati példákkal illusztrálva használatát.

Az aszinkron kontextus propagáció megértése

Az aszinkron kontextus propagáció arra a képességre utal, hogy a kontextusinformációkat (pl. kérésazonosítók, felhasználói hitelesítési adatok, korrelációs azonosítók) fenntartsuk és továbbítsuk az aszinkron műveleteken keresztül. Megfelelő kontextus propagáció nélkül nehézzé válik a kérések nyomon követése, a naplók korrelálása és a teljesítményproblémák diagnosztizálása az elosztott rendszerekben.

A kontextuskezelés hagyományos megközelítései gyakran a kontextusobjektumok explicit átadásán alapulnak a függvényhívásokon keresztül, ami terjengős és hibalehetőségeket rejtő kódhoz vezethet. Az AsyncLocalStorage elegánsabb megoldást kínál azáltal, hogy lehetővé teszi a kontextusadatok tárolását és lekérdezését egyetlen végrehajtási kontextuson belül, még az aszinkron műveleteken keresztül is.

Az AsyncLocalStorage bemutatása

Az AsyncLocalStorage egy beépített Node.js modul (a Node.js v14.5.0 verzió óta elérhető), amely lehetővé teszi az adatok tárolását, amelyek egy aszinkron művelet élettartamára lokálisak. Lényegében egy olyan tárolóhelyet hoz létre, amely megmarad az await hívások, a promise-ok és más aszinkron határok között. Ez lehetővé teszi a fejlesztők számára, hogy hozzáférjenek és módosítsák a kontextusadatokat anélkül, hogy azokat explicit módon továbbadnák.

Az AsyncLocalStorage főbb jellemzői:

• Automatikus kontextus propagáció: Az AsyncLocalStorage-ben tárolt értékek automatikusan propagálódnak az aszinkron műveletek között ugyanazon végrehajtási kontextuson belül.
• Egyszerűsített kód: Csökkenti a kontextusobjektumok explicit átadásának szükségességét a függvényhívásokon keresztül.
• Javított megfigyelhetőség: Megkönnyíti a kérések nyomon követését és a naplók, valamint metrikák korrelációját.
• Szálbiztosság: Szálbiztos hozzáférést biztosít a kontextusadatokhoz az aktuális végrehajtási kontextuson belül.

Az AsyncLocalStorage felhasználási esetei

Az AsyncLocalStorage számos forgatókönyvben értékes, többek között:

• Kérések nyomon követése: Egyedi azonosító hozzárendelése minden bejövő kéréshez és annak propagálása a kérés teljes életciklusa során nyomkövetési célokból.
• Hitelesítés és jogosultságkezelés: Felhasználói hitelesítési adatok (pl. felhasználói azonosító, szerepkörök, engedélyek) tárolása a védett erőforrásokhoz való hozzáféréshez.
• Naplózás és auditálás: Kérésspecifikus metaadatok csatolása a naplóüzenetekhez a jobb hibakeresés és auditálás érdekében.
• Teljesítményfigyelés: A különböző komponensek végrehajtási idejének követése egy kérésen belül a teljesítményelemzéshez.
• Tranzakciókezelés: Tranzakciós állapot kezelése több aszinkron műveleten keresztül (pl. adatbázis-tranzakciók).

Gyakorlati példa: Kérés nyomkövetés az AsyncLocalStorage segítségével

Illusztráljuk, hogyan használható az AsyncLocalStorage kéréskövetésre egy egyszerű Node.js alkalmazásban. Létrehozunk egy middleware-t, amely egyedi azonosítót rendel minden bejövő kéréshez, és elérhetővé teszi azt a kérés teljes életciklusa alatt.

Kód példa

Először telepítse a szükséges csomagokat (ha szükséges):

            npm install uuid express
            

              
                Copy
              
            
          

Itt a kód:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware to assign a request ID and store it in AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simulate an asynchronous operation
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Route handler
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

Ebben a példában:

1. Létrehozunk egy AsyncLocalStorage példányt.
2. Definiálunk egy middleware-t, amely egyedi azonosítót rendel minden bejövő kéréshez az uuid könyvtár segítségével.
3. Az asyncLocalStorage.run() metódust használjuk a kéréskezelő futtatásához az AsyncLocalStorage kontextusában. Ez biztosítja, hogy az AsyncLocalStorage-ben tárolt értékek elérhetők legyenek a kérés teljes életciklusa alatt.
4. A middleware-en belül a kérésazonosítót az AsyncLocalStorage-ben tároljuk az asyncLocalStorage.getStore().set('requestId', requestId) segítségével.
5. Definiálunk egy doSomethingAsync() aszinkron függvényt, amely egy aszinkron műveletet szimulál, és lekéri a kérésazonosítót az AsyncLocalStorage-ből.
6. Az útvonalkezelőben lekérjük a kérésazonosítót az AsyncLocalStorage-ből, és belefoglaljuk a válaszba.

Amikor futtatja ezt az alkalmazást, és kérést küld a http://localhost:3000 címre, látni fogja, hogy a kérésazonosító mind az útvonalkezelőben, mind az aszinkron függvényben naplózásra kerül, ami azt mutatja, hogy a kontextus megfelelően propagálódott.

Magyarázat

• AsyncLocalStorage példány: Létrehozunk egy AsyncLocalStorage példányt, amely a kontextusadatainkat fogja tárolni.
• Middleware: A middleware minden bejövő kérést elfog. Generál egy UUID-t, majd az asyncLocalStorage.run segítségével futtatja a kéréskezelési lánc többi részét *ezen* a tároló kontextusán *belül*. Ez kulcsfontosságú; biztosítja, hogy a lánc későbbi elemei hozzáférjenek a tárolt adatokhoz.
• asyncLocalStorage.run(new Map(), ...): Ez a metódus két argumentumot fogad el: egy új, üres Map-et (használhat más adatstruktúrákat is, ha az a kontextusának megfelelőbb) és egy visszahívó függvényt. A visszahívó függvény tartalmazza azt a kódot, amelynek az aszinkron kontextuson belül kell lefutnia. Bármely, ezen a visszahívón belül indított aszinkron művelet automatikusan örökli a Map-ben tárolt adatokat.
• asyncLocalStorage.getStore(): Ez visszaadja azt a Map-et, amelyet az asyncLocalStorage.run-nak átadtunk. Ezt használjuk a kérésazonosító tárolására és lekérésére. Ha a run nem lett meghívva, ez undefined-et ad vissza, ezért fontos, hogy a run-t a middleware-en belül hívjuk meg.
• Aszinkron függvény: A doSomethingAsync függvény egy aszinkron műveletet szimulál. Kulcsfontosságú, hogy bár aszinkron (a setTimeout használatával), mégis hozzáfér a kérésazonosítóhoz, mert az asyncLocalStorage.run által létrehozott kontextuson belül fut.

Haladó használat: Kombinálás naplózó könyvtárakkal

Az AsyncLocalStorage integrálása naplózó könyvtárakkal (mint a Winston vagy a Pino) jelentősen javíthatja az alkalmazások megfigyelhetőségét. A kontextusadatok (pl. kérésazonosító, felhasználói azonosító) naplóüzenetekbe való injektálásával könnyedén korrelálhatja a naplókat és követheti a kéréseket a különböző komponensek között.

Példa a Winstonnal

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modified)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Log the incoming request
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

Ebben a példában:

• Létrehozunk egy Winston logger példányt, és úgy konfiguráljuk, hogy minden naplóüzenetbe belefoglalja a kérésazonosítót az AsyncLocalStorage-ből. A kulcsfontosságú rész a winston.format.printf, amely lekéri a kérésazonosítót (ha elérhető) az AsyncLocalStorage-ből. Ellenőrizzük, hogy az asyncLocalStorage.getStore() létezik-e, hogy elkerüljük a hibákat, amikor egy kérés kontextusán kívül naplózunk.
• Frissítjük a middleware-t, hogy naplózza a bejövő kérés URL-jét.
• Frissítjük az útvonalkezelőt és az aszinkron függvényt, hogy a konfigurált logger segítségével naplózzanak üzeneteket.

Mostantól minden naplóüzenet tartalmazni fogja a kérésazonosítót, ami megkönnyíti a kérések nyomon követését és a naplók korrelálását.

Alternatív megközelítések: cls-hooked és Async Hooks

Mielőtt az AsyncLocalStorage elérhetővé vált, olyan könyvtárakat, mint a cls-hooked, gyakran használtak az aszinkron kontextus propagációjára. A cls-hooked az Async Hooks-ot (egy alacsonyabb szintű Node.js API) használja hasonló funkcionalitás eléréséhez. Bár a cls-hooked még mindig széles körben használatos, az AsyncLocalStorage általában előnyben részesítendő a beépített jellege és a jobb teljesítménye miatt.

Async Hooks (async_hooks)

Az Async Hooks egy alacsonyabb szintű API-t biztosít az aszinkron műveletek életciklusának követésére. Bár az AsyncLocalStorage az Async Hooks-ra épül, az Async Hooks közvetlen használata gyakran bonyolultabb és kevésbé teljesítményes. Az Async Hooks inkább nagyon specifikus, haladó felhasználási esetekre alkalmas, ahol finomhangolt vezérlés szükséges az aszinkron életciklus felett. Kerülje az Async Hooks közvetlen használatát, hacsak nem feltétlenül szükséges.

Miért részesítsük előnyben az AsyncLocalStorage-t a cls-hooked-dal szemben?

• Beépített: Az AsyncLocalStorage a Node.js magjának része, így nincs szükség külső függőségekre.
• Teljesítmény: Az AsyncLocalStorage általában teljesítményesebb, mint a cls-hooked az optimalizált implementációja miatt.
• Karbantartás: Mint beépített modul, az AsyncLocalStorage-t aktívan karbantartja a Node.js core csapata.

Megfontolások és korlátok

Bár az AsyncLocalStorage egy erőteljes eszköz, fontos tisztában lenni a korlátaival:

• Kontextushatárok: Az AsyncLocalStorage csak ugyanazon a végrehajtási kontextuson belül propagálja a kontextust. Ha adatokat ad át különböző folyamatok vagy szerverek között (pl. üzenetsorokon vagy gRPC-n keresztül), akkor is explicit módon kell szerializálnia és deszerializálnia a kontextusadatokat.
• Memóriaszivárgások: Az AsyncLocalStorage helytelen használata potenciálisan memóriaszivárgáshoz vezethet, ha a kontextusadatok nincsenek megfelelően eltakarítva. Győződjön meg arról, hogy helyesen használja az asyncLocalStorage.run() metódust, és kerülje a nagy mennyiségű adat tárolását az AsyncLocalStorage-ben.
• Bonyolultság: Bár az AsyncLocalStorage egyszerűsíti a kontextus propagációját, bonyolultabbá is teheti a kódot, ha nem használják óvatosan. Győződjön meg arról, hogy a csapata érti a működését és követi a bevált gyakorlatokat.
• Nem helyettesíti a globális változókat: Az AsyncLocalStorage *nem* helyettesíti a globális változókat. Kifejezetten a kontextus propagálására tervezték egyetlen kérésen vagy tranzakción belül. Túlzott használata szorosan csatolt kódhoz vezethet és megnehezítheti a tesztelést.

Bevált gyakorlatok az AsyncLocalStorage használatához

Az AsyncLocalStorage hatékony használatához vegye figyelembe a következő bevált gyakorlatokat:

• Használjon middleware-t: Használjon middleware-t az AsyncLocalStorage inicializálásához és a kontextusadatok tárolásához minden kérés elején.
• Minimális adatot tároljon: Csak a lényeges kontextusadatokat tárolja az AsyncLocalStorage-ben a memóriaterhelés minimalizálása érdekében. Kerülje a nagy objektumok vagy érzékeny információk tárolását.
• Kerülje a közvetlen hozzáférést: Az AsyncLocalStorage-hez való hozzáférést jól definiált API-k mögé zárja be a szoros csatolás elkerülése és a kód karbantarthatóságának javítása érdekében. Hozzon létre segédfüggvényeket vagy osztályokat a kontextusadatok kezelésére.
• Vegye figyelembe a hibakezelést: Implementáljon hibakezelést, hogy elegánsan kezelje azokat az eseteket, amikor az AsyncLocalStorage nincs megfelelően inicializálva.
• Teszteljen alaposan: Írjon egység- és integrációs teszteket annak biztosítására, hogy a kontextus propagáció a várt módon működik.
• Dokumentálja a használatot: Világosan dokumentálja, hogyan használják az AsyncLocalStorage-t az alkalmazásban, hogy segítse a többi fejlesztőt a kontextus propagációs mechanizmus megértésében.

Integráció az OpenTelemetry-vel

Az OpenTelemetry egy nyílt forráskódú megfigyelhetőségi keretrendszer, amely API-kat, SDK-kat és eszközöket biztosít a telemetriai adatok (pl. nyomkövetések, metrikák, naplók) gyűjtéséhez és exportálásához. Az AsyncLocalStorage zökkenőmentesen integrálható az OpenTelemetry-vel a nyomkövetési kontextus automatikus propagálásához az aszinkron műveleteken keresztül.

Az OpenTelemetry nagymértékben támaszkodik a kontextus propagációra a nyomkövetések korrelálásához a különböző szolgáltatások között. Az AsyncLocalStorage használatával biztosíthatja, hogy a nyomkövetési kontextus megfelelően propagálódjon a Node.js alkalmazásában, lehetővé téve egy átfogó elosztott nyomkövetési rendszer kiépítését.

Sok OpenTelemetry SDK automatikusan használja az AsyncLocalStorage-t (vagy a cls-hooked-ot, ha az AsyncLocalStorage nem elérhető) a kontextus propagációjához. Ellenőrizze a választott OpenTelemetry SDK dokumentációját a konkrét részletekért.

Összegzés

Az AsyncLocalStorage egy értékes eszköz az aszinkron kontextus propagáció kezelésére a szerveroldali JavaScript alkalmazásokban. A kérések nyomon követésére, hitelesítésre, naplózásra és más felhasználási esetekre való alkalmazásával robusztusabb, megfigyelhetőbb és karbantarthatóbb alkalmazásokat építhet. Bár léteznek alternatívák, mint a cls-hooked és az Async Hooks, az AsyncLocalStorage általában az előnyben részesített választás a beépített jellege, teljesítménye és egyszerű használata miatt. Ne feledje követni a bevált gyakorlatokat, és legyen tisztában a korlátaival, hogy hatékonyan kihasználhassa képességeit. A kérések követésének és az események aszinkron műveleteken keresztüli korrelálásának képessége kulcsfontosságú a skálázható és megbízható rendszerek építéséhez, különösen a mikroszolgáltatási architektúrákban és a komplex elosztott környezetekben. Az AsyncLocalStorage használata segít elérni ezt a célt, ami végső soron jobb hibakereséshez, teljesítményfigyeléshez és általános alkalmazás-egészséghez vezet.